Shareware Grab Bag/Shareware Grab Bag.iso/007/ratbas.arc/RATBAS.UM

Text File | 1982-08-10 | 9.6 KB | 349 lines

               THE RATBAS LANGUAGE

RATBAS (rhymes with "fat case") stands for "Rational Basic". It is a
language designed to provide some of the advantages of structured
languages (e.g. Pascal) but to allow simple and rapid translation to
Microsoft BASIC for the IBM Personal Computer.

A RatBas program consists of lines written in standard BASIC and lines
using features unique to RatBas. The latter are "flagged" for the
translator by a right bracket (]) at the end of the line. Lines not
ending with a right bracket are inserted in the BASIC program with
no change except the possible addition of a line number.

To translate a RATBAS program to an equivalent BASIC program, simply
"run it through" program RT.

For example:

      A> RT
         RatBas Program?  zilch;

This will produce a basic program under the name ZILCH.BAS. For
further information, see the entry under RT in the User's Manual.

The rules for RATBAS are relatively simple.

No line numbers are required (or allowed). RT will provide them as
needed.

Upper or lower case characters are allowed. Blank lines may be included.

The initial portion of the program should consist of declarations
and/or dimension statements. No executable statement should be
included.

The next portion should consist of PROCEDURES. These are equivalent to
BASIC subroutines but have names. A procedure is declared in the
following manner:

       PROCEDURE procedure-name]

For example:

       PROCEDURE GetFile]

In all such statements, the right bracket must be the last character
in the (logical) line.

The end of a procedure is identified by:

     PEND]

To invoke a procedure, simply give its name, followed by a right
bracket at the end of a line. For example:

     GetFile]

     If not done then GetFile]

Upper and lower case may be used in procedure names (the translator
considers all characters in a procedure name to be upper case whether
they are or not).

A procedure reference (call) can appear at the end of any BASIC statement
as long as GOSUB ---  would be legal in the position.

A procedure may call another procedure but the called procedure must
precede the one calling it in the program file.

The name ERROR is reserved. If a procedure named ERROR is included in
a RatBas program, it will be invoked automatically in the event of an
error when the BASIC program is run. After code in the  ERROR procedure
has been executed, the BASIC program will resume at the statement
following the one causing the error condition.

After all procedures have been declared, the file should have a line
declaring the program:

     PROGRAM]

Following this come the statements for the main program, including any
statements that call procedures.

In a procedure or the main program one may use RATBAS "if blocks"
of the form:

      If -------  then]
        .
        .
      Ifend!

  or:


        If ---------- then]
             .
             .
           else]
             .
             .
         ifend]

Note that "ifend" must be written as one word. The material between IF]
and THEN] can be any legal BASIC construct.

Two pre-declared values are TRUE and FALSE. They may be used in
comparisons or for assignments. For example:

    if (a>b) then notdone=true

All variables beginning with i,j,k,l,m or n will be considered
integers. This may be changed on a variable-by-variable basis by using
extended variable names (e.g. $, etc.) Alternatively, a DEF-
statement may be included to override the default.

The BASIC program produced by RT will contain the procedures with line
numbers that are even multiples of 100. A list of procedures, with
their line numbers, will begin at line number 20000.

RatBas programs may also include CASE statements of the form:

         CASE <lhs> of]
             <rhs1> :]
                      <statements-1>
             <rhs2> :]
                      <statements-2>
             OTHERWISE]
                      <statements-3>
          CEND]

<lhs> can be any statement that is legal in an IF statement; as can
<rhs>. The effect of this structure is as follows:

        IF <lhs>=<rhs1> then <statements-1>
        IF <lhs>=<rhs2> then <statements-2>
        Otherwise   <statements-3>

If OTHERWISE] is omitted, the translator will insert an OTHERWISE
section with no executable statements.

Note that in a CASE statement, alternative selections are evaluated in
order. For efficiency, the more likely alternatives should be placed
first.

Procedures may include arguments. Their use can be best described
by example:

      PROCEDURE Sum (x,y,v:z)]
            z=x+y
      PEND]
        .
        .
        .
      PROGRAM]
        .
       SUM (a, b+3, c)
        .

In the procedure declaration, only unsubscripted variable names may be
given. These are global (in the sense that they are the same as other
variables in the program). The effect of the foregoing is to produce a
basic program withe following statements for the "call":

     x=a
     y=b+3
     z=c
     GOSUB ..... ' SUM
     c=z

Note that only the third argument is re-assigned when the procedure
(subroutine) is completed (since it is declared "variable" in the
procedure) . Expressions may be used in a procedure call for any
argument not declared variable.

Program RT allows the use of INCLUDE files. One need only include a
line of the form:

       INCLUDE Zilch]

to indicate that the named file is to be inserted at this point as if
it had been part of the RatBAS program. If no disk drive is given, the
default disk is assumed; if no extension is given, .INC is assumed.

The following program demonstrates the use of most of the features of
RATBAS. It is designed to read a file in the DIF format (produced by
VisiCalc programs) and make a copy in the same format.

 -------------------------------------------------------------------

'Include file RWDIF.INC
'routines to read and write DIF files

'CONSTANTS
    quote$=chr$(34)
    nul$=chr$(34)+chr$(34)

PROCEDURE WriteHeader(numvecs,numtups)]
'writes header for DIF file (#2)
    'write standard table header
    print #2, "TABLE"
    print #2,"0,1"
    print #2,nul$
    'write number of vectors
    print #2,"VECTORS"
    print #2,"0,";numvecs
    print #2,nul$
    'write number of tuples
    print #2,"TUPLES"
    print #2,"0,";numtups
    print #2,nul$
    'write standard data header
    print #2,"DATA"
    print #2,"0,0"
    print #2,nul$
PEND]

PROCEDURE WriteBOT]
'writes beginning-of-tuple header
    print #2,"-1,0"
    print #2,"BOT"
PEND]

PROCEDURE WriteEOD]
'writes an end-of-data record
    print #2,"-1,0"
    print #2,"EOD"
PEND]

PROCEDURE WriteValue]
'writes VALUE
    print #2,"0,";value
    print #2,"V"
PEND]

PROCEDURE WriteString]
'writes STG$
    print #2,"1,0"
    print #2,quote$;stg$;quote$
PEND]

PROCEDURE ReadTriplet]
'reads title$,ntype,number,string$
    input #1,title$
    input #1,ntype,number
    input #1,stg$
PEND]

PROCEDURE ReadHeader(v:numvecs,v:numtups,v:ok)]
'reads header and gets number of vectors and tuples
'ok=true if a DIF file, false if not
    'set ok=false until all set
    ok=false
    'header
    ReadTriplet]
    if title$<>"TABLE" then return
    'vectors
    ReadTriplet]
    if title$<>"VECTORS" then return
    numvecs=number
    'tuples
    ReadTriplet]
    if title$<>"TUPLES" then return
    numtups=number
    'data header
    ReadTriplet]
    if title$<>"DATA" then return
    'if made it to here, file is OK
    ok=true
PEND]

PROCEDURE ReadPair]
' reads ntype, value, stg$
    input #1, ntype, value
    input #1, stg$
PEND]

PROCEDURE ReadNextCell]
'reads next cell
' sets type$ = "a"or "r"
'    if "a", stg$ is string
'    if "r", val is real value
    'read pair
    ReadPair]
    case ntype of]
        0 :]
           type$="r"
        1 :]
           type$="a"
        cend]
PEND]

PROGRAM]
    'reads one dif file and makes a copy
    input "source file: ",file1name$
    open file1name$ for input as #1
    input "destination file: ",file2name$
    open file2name$ for output as #2
    'headers
    ReadHeader]
        print numvecs;" Vectors,    ";numtups;" Tuples"
    WriteHeader]
    'tuples
    for i=1 to numtups
    ' BOT
        readpair]
        writeBOT]
    'entries
        for j=1 to numvecs
        ReadNextCell]
            case type$ of]
            "r" :]
                 WriteValue]
            "a" :]
                 WriteString]
                cend]
        next j
    next i
    'end-of-data
    WriteEOD]
END

 --------------------------------------------------------------------


Since BASIC has neither local variables nor true arguments for
multi-line procedures, some care is needed if programs are to be
written in a truly modular fashion. One helpful procedure is to name
all "local" variables in a procedure with the name of the procedure.
Thus in procedure Zilch:

      i.zilch
      x.zilch

     etc..

If names with decimal points are used only in this way, few if any
conflicts should arise.

As a practical matter, one may draft a program in RATBAS, then
translate it to BASIC for use with the interpreter. A printed copy of
the RATBAS program should be made for posting changes. Then the BASIC
program should be debugged, with changes posted to the printed version
of the RATBAS program. When the BASIC program is working, the RATBAS
version should be modified as apropriate. Then RT should be used to
produce a version with no unnecessary line numbers (using the "/N"
option). The latter can then be compiled with the BASIC compiler
(using the "/N" option) to produce efficient compiled code.